home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / SelHandler.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  8.5 KB  |  294 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/SelHandler.man,v 1.4 91/12/06 10:39:31 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_CreateSelHandler tk
  189. .BS
  190. .SH NAME
  191. Tk_CreateSelHandler \- arrange to handle requests for the primary selection
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tk.h>\fR
  195. .sp
  196. \fBTk_CreateSelHandler\fR(\fItkwin, target, proc, clientData, format\fR)
  197. .SH ARGUMENTS
  198. .AS Tk_SelectionProc clientData
  199. .AP Tk_Window tkwin in
  200. Window for which \fIproc\fR will provide selection information.
  201. .AP Atom target in
  202. Form in which \fIproc\fR can provide the selection (e.g. STRING
  203. or FILE_NAME).  Corresponds to \fItype\fR arguments in \fBselection\fR
  204. commands.
  205. .AP Tk_SelectionProc *proc in
  206. Procedure to invoke whenever the selection is owned by \fItkwin\fR
  207. and the selection contents are requested in the format given by
  208. \fItarget\fR.
  209. .AP ClientData clientData in
  210. Arbitrary one-word value to pass to \fIproc\fR.
  211. .AP Atom format in
  212. If the selection requestor isn't in this process, \fIformat\fR determines
  213. the representation used to transmit the selection to its
  214. requestor.
  215. .BE
  216.  
  217. .SH DESCRIPTION
  218. .PP
  219. \fBTk_CreateSelHandler\fR arranges for a particular procedure
  220. (\fIproc\fR) to be called whenever the selection is owned by
  221. \fItkwin\fR and the selection contents are requested in the
  222. form given by \fItarget\fR.  \fITarget\fR should be one of
  223. the entries defined in the left column of Table 2 of the
  224. X Inter-Client Communication Conventions Manual (ICCCM) or
  225. any other form in which an application is willing to present
  226. the selection.  The most common form is STRING.
  227. .PP
  228. \fIProc\fR should have arguments and result that match the
  229. type \fBTk_SelectionProc\fR:
  230. .nf
  231. .RS
  232. typedef int Tk_SelectionProc(
  233. .RS
  234. ClientData \fIclientData\fR,
  235. int \fIoffset\fR,
  236. char *\fIbuffer\fR,
  237. int \fImaxBytes\fR);
  238. .RE
  239. .RE
  240. .fi
  241. The \fIclientData\fP parameter to \fIproc\fR is a copy of the
  242. \fIclientData\fP argument given to \fBTk_CreateSelHandler\fR.
  243. Typically, \fIclientData\fR points to a data
  244. structure containing application-specific information that is
  245. needed to retrieve the selection.  \fIOffset\fR specifies an
  246. offset position into the selection, \fIbuffer\fR specifies a
  247. location at which to copy information about the selection, and
  248. \fImaxBytes\fR specifies the amount of space available at
  249. \fIbuffer\fR.  \fIProc\fR should place a NULL-terminated string
  250. at \fIbuffer\fR containing \fImaxBytes\fR or fewer characters
  251. (not including the terminating NULL), and it should return a
  252. count of the number of non-NULL characters stored at
  253. \fIbuffer\fR.  If the selection no longer exists (e.g. it once
  254. existed but the user deleted the range of characters containing
  255. it), then \fIproc\fR should return -1.
  256. .PP
  257. When transferring large selections, Tk will break them up into
  258. smaller pieces (typically a few thousand bytes each) for more
  259. efficient transmision.  It will do this by calling \fIproc\fR
  260. one or more times, using successively higher values of \fIoffset\fR
  261. to retrieve successive portions of the selection.  If \fIproc\fR
  262. returns a count less than \fImaxBytes\fR it means that the entire
  263. remainder of the selection has been returned.  If \fIproc\fR's return
  264. value is \fImaxBytes\fR it means there may be additional information
  265. in the selection, so Tk must make another call to \fIproc\fR to
  266. retrieve the next portion.
  267. .PP
  268. \fIProc\fR always returns selection information in the form of a
  269. character string.  However, the ICCCM allows for information to
  270. be transmitted from the selection owner to the selection requestor
  271. in any of several formats, such as a string, an array of atoms, an
  272. array of integers, etc.  The \fIformat\fR argument to
  273. \fBTk_CreateSelHandler\fR indicates what format should be used to
  274. transmit the selection to its requestor (see the middle column of
  275. Table 2 of the ICCCM for examples).  If \fIformat\fR is not
  276. STRING, then Tk will take the value returned by \fIproc\fR and divided
  277. it into fields separated by white space.  If \fIformat\fR is ATOM,
  278. then Tk will return the selection as an array of atoms, with each
  279. field in \fIproc\fR's result treated as the name of one atom.  For
  280. any other value of \fIformat\fR, Tk will return the selection as an
  281. array of 32-bit values where each field of \fIproc\fR's result is
  282. treated as a number and translated to a 32-bit value.  In any event,
  283. the \fIformat\fR atom is returned to the selection requestor along
  284. with the contents of the selection.
  285. .PP
  286. At present there is no way to delete a selection handler except
  287. by deleting the window with which it is associated.  However, if
  288. \fBTk_CreateSelHandler\fR is called when there already exists a
  289. handler for \fItarget\fR on \fItkwin\fR, then the existing handler
  290. is replaced with a new one.
  291.  
  292. .SH KEYWORDS
  293. format, handler, selection, target
  294.